@1ucian0 Need clarification on some colors.

I have no opinion here. @nonhermitian ?

@1ucian0 Since the color outline is still under discussion. Should I run the binder as in #4544 or put it on hold?

Another question: there are 2 active PRs right now to solve #5032. Should we keep updating our code simultaneously like this?

@enavarro51 @1ucian0 here's an overview of the colors: https://quantum-computing.ibm.com/docs/iqx/operations-glossary.

Classical gates are dark blue, this includes also MCX and DCX, since they are also a classical operation.
Phase gates (this means diagonal matrices) are light blue, this includes also P, T and S as well as their inverses. Non-unitary operations, such as c_if, barrier, measure and reset are grey. All other quantum gates are dark red, i.e. custom to_gate etc.

So here's the overview again, including the gates @enavarro51 mentioned above:

Classical: Dark blue
I, X, CX, CCX, C3X, C4X, any MCX, DCX, Swap, CSwap, and controlled versions of these.

Phase gates: Cyan
Z, S, Sdg, T, Tdg, P, U1

Hadamard: Red
H

Non-unitary: Grey
Reset, c_if, Barrier, Measure

Other: Dark red
Every gate not mentioned above, also arbitrary custom gates, U, U3, GMS, SX, etc.

In principle, controlled versions of the phase gates should also be cyan as controlling a diagonal gates is still diagonal. But this might be a little more complicated to do and we can stick to just making the single qubit ones cyan for now and the controlled versions have the default red.

Another question: there are 2 active PRs right now to solve #5032. Should we keep updating our code simultaneously like this?

I don't think this makes a lot of sense, it'll just duplicate the work and we'll be only able to merge one 🤔

@Cryoris Thanks for the great info. This clarifies a lot.

I have a proposal that will get us well on the way to a true user-defined colormap/style sheet and can be done as an extension of this PR.

There already exists a rudimentary style sheet idea in the mpl drawer, but it is incomplete and buggy. In fact, I'm relatively sure there is nobody using the style capability for 'displaycolor' since it would only work if they knew the source and knew one specific way to set it up. It would be fairly easy to make the 'displaycolor' option available to users.

In addition there is a user-configurable selection in the settings.conf file for 'circuit_mpl_style', but the only option that works in the mpl code is 'default', which is what you would get anyway. So I think we should add 'original' - for current colors, 'iqx' - for the new iqx color map, and 'bw' for black & white. Then we just need 3 style classes in qcstyle to do it all.

Also there is an issue with font color, since there are a lot of border cases where black or white could both work, so I'd like to make the dispcol value a (color, font_color) tuple which would make the qcstyle code much easier to maintain. Unlike the old version of mpl, which had 35 references to dispcol, the new version has 3 (pat myself on the back :)), so updating this in mpl would be easy as well, and can be made backward compatible, in case anyone was using the 'displaycolor' option.

This would be phase 1 on the path to full user colormap definition. It would,

• Provide 3 color styles, original, iqx, and bw, selectable by the user
• Create a structure for future imports of user-styles
• Allow the user to configure specific gate colors through the style 'displaycolor' param to draw

Phase 2 would create a location for colormaps, maybe .qiskit, and let users build whatever they wanted and import somehow into mpl, either as an import or a file read.

I'm happy to work with @galeinston on this. It really should be fairly straightforward.

I like the idea of 3 color styles and how @enavarro51 planned out to make it work. It's be my pleasure to work on the proposed extension.

I have a proposal that will get us well on the way to a true user-defined colormap/style sheet and can be done as an extension of this PR.

There already exists a rudimentary style sheet idea in the mpl drawer, but it is incomplete and buggy. In fact, I'm relatively sure there is nobody using the style capability for 'displaycolor' since it would only work if they knew the source and knew one specific way to set it up. It would be fairly easy to make the 'displaycolor' option available to users.

FWIW, we do try to document the style sheet style parameter which does let users define a full style dict/ json for the drawer to use: https://qiskit.org/documentation/stubs/qiskit.visualization.circuit_drawer.html#qiskit.visualization.circuit_drawer But I agree it could definitely use some love.

In addition there is a user-configurable selection in the settings.conf file for 'circuit_mpl_style', but the only option that works in the mpl code is 'default', which is what you would get anyway. So I think we should add 'original' - for current colors, 'iqx' - for the new iqx color map, and 'bw' for black & white. Then we just need 3 style classes in qcstyle to do it all.

I agree with this, instead of changing the default this PR should be adding a 3rd iqx class to qcstyle.py. For the settings.conf we should just iqx to list of valid default styles in qiskit/user_config.py I think what you're calling original here should probably stay as default (just for backwards compat reasons. Besides the settings.conf file, default is the kwarg default value for the draw functions. If we do rename default to original we'll still have to correctly handle when default is set as the value in the settings.conf and kwarg.

Also there is an issue with font color, since there are a lot of border cases where black or white could both work, so I'd like to make the dispcol value a (color, font_color) tuple which would make the qcstyle code much easier to maintain. Unlike the old version of mpl, which had 35 references to dispcol, the new version has 3 (pat myself on the back :)), so updating this in mpl would be easy as well, and can be made backward compatible, in case anyone was using the 'displaycolor' option.

This would be phase 1 on the path to full user colormap definition. It would,

* Provide 3 color styles, original, iqx, and bw, selectable by the user

* Create a structure for future imports of user-styles

* Allow the user to configure specific gate colors through the style 'displaycolor' param to draw

I think this last point might be out of scope for this PR. I'm assuming by this you're talking about doing something like:

circuit_drawer(qc, output='mpl', style={'displaycolor': {'h': '#ff0080'}})

and instead of the current behavior where only hadamard gates would have a color set, it changes the default color in the configured style sheet to use the fuschia for hadmard and everything remains the same. We should do this piece separately because there are backwards compat implications for changing this behavior. We can quickly add a new stylesheet to the drawer for the iqx theme (and fix the font color thing as you described) without this piece.

Phase 2 would create a location for colormaps, maybe .qiskit, and let users build whatever they wanted and import somehow into mpl, either as an import or a file read.

My thinking on this was to either do it one of 2 ways:

1. We add a mpl_stylesheet dir to ~/.qiskit (and allow it to be configured via an env var and entry in the settings.conf). Then we just locate all the .json files in that dir and use the filename as the style name.
2. We add a config section to the settings.conf for mpl style sheetsheet where we add entries for style name and path to json. For example:

[mpl_stylesheets]
custom1 = ~/custom_mpl_style.json
custom2 = ~/special_mpl_style.json

I'm leaning more towards the later, because it also gives us this flexibility for more easily distinguishing style sheets between the mpl circuit drawer, the pulse drawer (and possibly the mpl state visualizations too). The pulse visualizer has the same kind of style sheets as the circuit drawer and whatever we expose for the circuit drawer we're also going to want to work for the pulse visualizer too.

I agree with this, instead of changing the default this PR should be adding a 3rd iqx class to qcstyle.py. For the settings.conf we should just iqx to list of valid default styles in qiskit/user_config.py I think what you're calling original here should probably stay as default (just for backwards compat reasons. Besides the settings.conf file, default is the kwarg default value for the draw functions. If we do rename default to original we'll still have to correctly handle when default is set as the value in the settings.conf and kwarg.

Using 'default' is fine.

I think this last point might be out of scope for this PR. I'm assuming by this you're talking about doing something like:
circuit_drawer(qc, output='mpl', style={'displaycolor': {'h': '#ff0080'}})
and instead of the current behavior where only hadamard gates would have a color set, it changes the default color in the configured style sheet to use the fuschia for hadmard and everything remains the same. We should do this piece separately because there are backwards compat implications for changing this behavior. We can quickly add a new stylesheet to the drawer for the iqx theme (and fix the font color thing as you described) without this piece.

There actually is not a backwards compat problem here. Someone can currently do what you show above, but if they put an 'x' gate in the circuit, the drawer would crash. The 'displaycolor' dict currently has to have an entry for every gate that's used. Not sure anybody really knows that.

What I'm proposing is doing the same thing, but not crashing. As you say, this would then change the 'h' color and leave all the rest the same. Don't think we need to worry about backwards compat if the previous behavior was a crash.

And making the (color, font_color) tuple can be backwards compat as well by checking if the value for 'h' is a string or tuple in the code. If a string, use the color and make the font_color either the default or what the user has defined in the style dict.
So the new way would now look like,
circuit_drawer(qc, output='mpl', style={'displaycolor': {'h': ('#ff0080', '#000000')}})
It's not real elegant for the user, but the capability is there and anything they were previously doing would still work.

All of this will require some doc changes, of course.

As to the phase 2, what you suggest looks fine and making it compatible with the pulse drawer would be great. Once this PR is done, we can create a new issue for phase 2.

@galeinston Are you on qiskit Slack?

Yup. I'm on Slack

Following @1ucian0 suggestion in #4544,I made this binder to test the MPL. I believe this link is still valid even after @enavarro51 and I update the code based on #5063 (comment) and #5063 (comment)
👇

Phase gates: Cyan
Z, S, Sdg, T, Tdg, P, U1

@Cryoris Just one more check. What about sx and sxdg. Are these phase gates? Thanks.

@galeinston Make sure to update the refs in /test/ipynb/mpl/references to match your gate colors. Or else you will have failing binder tests.

@Cryoris Just one more check. What about sx and sxdg. Are these phase gates? Thanks.

@enavarro51 SX and SXdg should be red, their matrix representation is not diagonal. I updated the list above 👍

Classical: Dark blue
I, X, CX, CCX, C3X, C4X, any MCX, DCX, Swap, CSwap, and controlled versions of these

@Cryoris Some (hopefully) last questions on colors.

• c3x and c4x are no longer active. You can't enter them as circuit.c3x and if you create a 3-control x, it returns mcx as the name.
• if you enter circuit.mcx it returns mcx_gray as the name. Should we add this to the color list?
• DCX, for example, can have an unlimited number of controls, so c6dcx could be a gate name. What we're trying to do here is a simple mapping of gate names to colors, which is what we have always done. Is it ok if we stop the number of controls for Dark Blue at some reasonable number like 2 (for other than X). So cdcx and ccdcx would be DarkBlue and any higher # of controls would be DarkRed? Similar for Swap?

@Cryoris I also have a question regarding the R-gate (as shown in the picture). I can't find it neither in Circuit Library document nor in IQX page, can you clarify if this gate has been deprecated/deleted?

We've made the following changes in this PR.

• First, all changes should be 100% backward compatible. We've only added functionality, not taken any away.
• There are now 3 color styles available - default, iqx, and bw. They can be set in one of 2 ways.
  • In the [Default] section of the settings.conf file in the ~/.qiskit dir, add circuit_mpl_style = '<style_name>'
  • In the draw() command add param style={'name': '<style_name>'}
• There needed to be some special mpl drawer code added to handle controlled classical gates, so iqx will not be as generic as other possible styles. The problem was with gate names like c5dcx, c6dcx, and onward.
• The dispcol dict in the style dict now sets colors as (gate_color, text_color). This allows the use of light and dark gate colors with black or white text. Actually someone could configure the style dict to do any combo, such as dark blue text on a yellow gate. The previous dispcol format of gate_color only still works, and will in that case use the 'gatetextcolor' for text.
• The style dict docs in quantumcircuit.py and circuit_visualization.py have been updated with the current dispcol, with explanation changes as well.
• A binder test was added for the iqx colors.
• A release note will be done once any replies to this comment have been addressed.

Phase 2 for the future,

• This PR creates 3 separate style classes in qcstyle.py. We envision that in future, this can be reduced to 1 default class and the additional styles would be read in from json files. I don't believe users should be allowed to modify these 3 styles directly, but they can copy these and create new styles of their own. Which brings up where to put things in the future.
  • I believe that default, iqx, and bw json style files should be part of qiskit, perhaps in the visualization directory.
  • User json files should go in a fixed place, perhaps in a styles dir under ~/.qiskit.
• The code for reading in the json files already exists, though there is only minimal error checking currently. Deciding on the locations for the files is the main issue.
• We might want to look at any possible special cases, like the controlled classical gates in iqx and see if any of these can be addressed in a generic way. Right now all a user can do with color, is change the colors of the specific gate names in dispcol.